applicationinsights

What is applicationinsights?

The applicationinsights npm package is a powerful tool for monitoring and diagnosing performance issues in your applications. It provides a range of features for collecting telemetry data, tracking custom events, and monitoring dependencies, among other capabilities.

What are applicationinsights's main functionalities?

Telemetry Client

The Telemetry Client allows you to track custom events and metrics. This example demonstrates how to set up the client and track a custom event.

const appInsights = require('applicationinsights');
appInsights.setup('YOUR_INSTRUMENTATION_KEY').start();
const client = appInsights.defaultClient;
client.trackEvent({ name: 'my custom event', properties: { customProperty: 'custom value' } });

Request Tracking

Request Tracking automatically collects and sends telemetry data for incoming HTTP requests. This example shows how to set up a basic HTTP server with request tracking enabled.

const appInsights = require('applicationinsights');
appInsights.setup('YOUR_INSTRUMENTATION_KEY').start();
const http = require('http');
http.createServer((req, res) => {
  res.writeHead(200, { 'Content-Type': 'text/plain' });
  res.end('Hello World\n');
}).listen(8080);

Dependency Tracking

Dependency Tracking allows you to monitor the performance and success of external dependencies. This example demonstrates how to manually track a dependency.

const appInsights = require('applicationinsights');
appInsights.setup('YOUR_INSTRUMENTATION_KEY').start();
const client = appInsights.defaultClient;
client.trackDependency({ target: 'http://example.com', name: 'GET /', data: 'http://example.com', duration: 100, resultCode: 200, success: true });

Exception Tracking

Exception Tracking captures and sends telemetry data for exceptions. This example shows how to track an exception.

const appInsights = require('applicationinsights');
appInsights.setup('YOUR_INSTRUMENTATION_KEY').start();
const client = appInsights.defaultClient;
try {
  throw new Error('Test error');
} catch (e) {
  client.trackException({ exception: e });
}

Other packages similar to applicationinsights

winston

Winston is a versatile logging library for Node.js. While it focuses more on logging rather than telemetry, it can be used to log events, errors, and other information. It does not provide the same level of built-in telemetry and performance monitoring as applicationinsights.

log4js

Log4js is another logging library for Node.js, inspired by the Java log4j library. It provides a variety of appenders for logging to different destinations. Like winston, it focuses on logging rather than telemetry and performance monitoring.

newrelic

New Relic is a comprehensive application performance monitoring tool that provides similar functionalities to applicationinsights, including telemetry, error tracking, and performance monitoring. It is a commercial product with a broader set of features and integrations.

datadog

Datadog is a monitoring and analytics platform for developers, IT operations teams, and business users. It offers extensive features for monitoring applications, including telemetry, performance metrics, and log management. It is a commercial product with a wide range of integrations and capabilities.

README

Application Insights for Node.js

This project provides a Visual Studio Application Insights SDK for Node.js. The SDK sends telemetry about the performance and usage of your live Node.js application to the Application Insights service. There you can analyze charts of request rates, response times, failures and dependencies, and diagnose issues using powerful search and aggregation tools.

The SDK provides automatic collection of incoming HTTP request rates and responses, performance counters (CPU, memory, RPS), and unhandled exceptions. In addition, you can add custom calls to track dependencies, metrics, or other events.

In versions of Node.js > 4.0 (and io.js > 3.3) the SDK provides automatic correlation of dependencies to requests (off by default, see Customized Usage below to enable).

Requirements

Install

npm install applicationinsights

Get an instrumentation key

Create an Application Insights resource where your telemetry will be displayed. This provides you with an instrumentation key that identifies the resource. (You can try the SDK without sending telemetry: set the instrumentation key to a non-empty string.)

Usage

This will enable request monitoring, unhandled exception tracking, and system performance monitoring (CPU/Memory/RPS).

import appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>").start();

The instrumentation key can also be set in the environment variable APPINSIGHTS_INSTRUMENTATIONKEY. If this is done, no argument is required when calling appInsights.setup() or appInsights.getClient().

Customized Usage

Enabling automatic correlation

import appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>")
    .setAutoDependencyCorrelation(true)
    // no telemetry will be sent until .start() is called
    .start();

Be sure to call require("applicationinsights") before your other imports. This allows the SDK to do patching necessary for tracking correlation state before other libraries use patched methods. If you encounter conflicts with other libraries doing similar patching, place this import below those libraries.

Disabling automatic collection

import appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>")
    .setAutoCollectRequests(false)
    .setAutoCollectPerformance(false)
    .setAutoCollectExceptions(false)
    .setAutoCollectDependencies(false)
    // no telemetry will be sent until .start() is called
    .start();

Custom monitoring

import appInsights = require("applicationinsights");
var client = appInsights.getClient();

client.trackEvent("custom event", {customProperty: "custom property value"});
client.trackException(new Error("handled exceptions can be logged with this method"));
client.trackMetric("custom metric", 3);
client.trackTrace("trace message");

Telemetry Processor

public addTelemetryProcessor(telemetryProcessor: (envelope: ContractsModule.Contracts.Envelope, context: { http.RequestOptions, http.ClientRequest, http.ClientResponse, correlationContext }) => boolean)

Adds a telemetry processor to the collection. Telemetry processors will be called one by one, in the order they were added, before the telemetry item is pushed for sending. If one of the telemetry processors returns false then the telemetry item will not be sent. If one of the telemetry processors throws an error then the telemetry item will not be sent.

All telemetry processors receive the envelope to modify before sending. They also receive a context object with relevant request information (if available) as well as the request storage object returned by appInsights.getCorrelationContext() (if automatic dependency correlation is enabled).

Example

Add the below code before you send any telemetry, it will remove stack trace information from any Exception reported by the SDK.

appInsights.client.addTelemetryProcessor((envelope) => {
    if (envelope.data.baseType === "Microsoft.ApplicationInsights.ExceptionData") {
        var data = envelope.data.baseData;
        if (data.exceptions && data.exceptions.length > 0) {
            for(var i = 0; i < data.exceptions.length; i++) {
                var exception = data.exceptions[i];
                exception.parsedStack = null;
                exception.hasFullStack = false;
            }
        }
    }
    return true;
});

Learn more about the telemetry API.

Using multiple instrumentation keys

import appInsights = require("applicationinsights");

// configure auto-collection with one instrumentation key
appInsights.setup("<instrumentation_key>").start();

// get a client for another instrumentation key
var otherClient = appInsights.getClient("<other_instrumentation_key>");
otherClient.trackEvent("custom event");

Examples

Tracking dependency

import appInsights = require("applicationinsights");
var client = appInsights.getClient();

var startTime = Date.now();
// execute dependency call
var endTime = Date.now();

var elapsedTime = endTime - startTime;
var success = true;
client.trackDependency("dependency name", "command name", elapsedTime, success);

Manual request tracking of all "GET" requests

var http = require("http");
var appInsights = require("applicationinsights");
appInsights.setup("<instrumentation_key>")
    .setAutoCollectRequests(false) // disable auto-collection of requests for this example
    .start();

// assign common properties to all telemetry sent from the default client
appInsights.client.commonProperties = {
    environment: process.env.SOME_ENV_VARIABLE
};

// track a system startup event
appInsights.client.trackEvent("server start");

// create server
var port = process.env.port || 1337
var server = http.createServer(function (req, res) {
    // track all "GET" requests
    if(req.method === "GET") {
        appInsights.client.trackRequest(req, res);
    }

    res.writeHead(200, { "Content-Type": "text/plain" });
    res.end("Hello World\n");
}).listen(port);

// track startup time of the server as a custom metric
var start = +new Date;
server.on("listening", () => {
    var end = +new Date;
    var duration = end - start;
    appInsights.client.trackMetric("StartupTime", duration);
});

Branches

• master contains the latest published release located on NPM.
• develop contains the code for the next release. Please send all pull requests to this branch.

Links

• Follow the latest Application Insights changes and announcements on ApplicationInsights Announcements
• Application Insights Home. The main repository for documentation of overall SDK offerings for all platforms.
• SDK Release Schedule

Contributing

Development environment

• Install dev dependencies

  npm install 
  

• (optional) Set an environment variable to your instrumentation key

  set APPINSIGHTS_INSTRUMENTATIONKEY=<insert_your_instrumentation_key_here>
  

• Run tests

  npm test
  

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [e-mail] with any additional questions or comments.